Linux Cubed Series 8: LINUX Games/Linux Cubed Series 8 - LINUX Games.iso/games/muds/pennmush.000/pennmush-1.50-p8-linux.tar/pennmush/README

Text File | 1993-04-21 | 23KB | 434 lines

============================================================================
                   User's Guide to PennMUSH
============================================================================

I.   Introduction
II.  Installation Guide (new users)
III. Conversion Guide (previous users)
IV.  Additional Options
V.   Trouble-shooting
VI.  Comments

============================================================================

I.   Introduction

     PennMUSH is a TinyMUD derivative, and one of the branches along the
MUSH line. "Vanilla" TinyMUSH, which added the "v" registers and functions
to the basic TinyMUD building commands, was written by Larry Foard. The
code was later expanded by Jin, of MicroMUSH. In January of 1991, MicroMUSH
changed its name to MicroMUSE, and the code there continued to develop
under the MUSE name. At that same point in time, Moonchilde took the last
public release of that code and began a series of improvements and extensions.

     That code was released as PernMUSH, named for the MUSH that Moonchilde
was running. The last released version of that code was version 1.15, at
the end of November 1991. PernMUSH itself had switched over to TinyMUSH 2.0,
which Moonchilde had co-written with Glenn Crocker (Wizard of TinyCWRU);
there was no longer a reason for Moonchilde to maintain this code.

     In January of 1992, Amberyl began working on the PernMUSH 1.15 code
release, for TinyKrynn. She took over the code, which no one was supporting,
and is continuing to work on extending this code, as well as improving its
compatibility with TinyMUSH 2.0.  She changed the name to PennMUSH
(named for her school, the University of Pennsylvania), to avoid the
confusion that resulted from PernMUSH actually running TinyMUSH 2.0.
The latest version of this code is generally running at the Belgariad,
at csa.bu.edu 4201.

     PennMUSH and TinyMUSH 2.0 are the only publicly available MUSH
distributions; other MUSHes have private hacks, but do not support
official distributions. PennMUSH is memory-based; TinyMUSH is
disk-based. PennMUSH can run in very little disk space, but very large
databases (25,000+ objects) can take up a prohibitive amount of
memory. TinyMUSH has a fairly large initial memory requirement,
and uses a lot of disk space, but has the advantage of being more
efficient, as well as a vastly slower rate of growth in memory usage,
once the database gets to about ten thousand or so objects.
It is possible to switch from PennMUSH to TinyMUSH, as well as vice
versa, so you are not "stuck" with any one code.

      TinyMUSH 2.0 patchlevels 6+ are capable of reading in databases from
PennMUSH versions 1.19 and earlier, and 1.50, with some tweaking, so if
you later want to switch codes, that option is available. In addition,
a program to convert TinyMUSH 2.0 databases to PennMUSH 1.50 format is
available from Amberyl via email, so it's possible to switch back as well.

      A MUSH manual should be available at caisr2.caisr.cwru.edu,
ftp.math.okstate.edu, primerd.prime.com, or from wherever you got this
code from. The manual should be numbered version 2.006 or higher.

      Enjoy!

============================================================================

II.  Installation (new users)

     DISCLAIMER: Before attempting to run a MUD of any sort, you should
have some reasonable knowledge of UNIX and C.  If you do not, it is
_strongly_ suggested that you learn UNIX and C to some reasonable level
of competency before attempting to set up a MUSH.

     The MUSH directories are organized fairly simply: source code is in
the top-level directory with RWHO-related stuff is in the RWHO directory
below it; all things related to running the game itself are in the "game"
directory below. That directory contains four subdirectories -- "data"
(current databases), "save" (backup databases), "txt" (text files), and
"log" (log files).

     First, copy Makefile.dist to Makefile, options.h.dist to options.h,
and bigrams.h.dist to bigrams.h.  (Unlike previous versions, version.h
is a standard file and does not need to be changed.)

     Then, edit options.h.  The file is fairly liberally commented.
You should definitely read the entire thing before figuring out what
you want to change.

     Ignore all the "ADD_<whatever>" config directives.  If you use
the database provided with this distribution, you will not need to
do any conversions, unless you choose to add the chat system.

     You will need to decide whether or not you want to use the chat
system. Once you add this into your database, you can't get rid of
it. If you don't ever want to use it, set the value of CHAT_SYSTEM
in options.h to 0.

     If you decide you want the chat system, set the value of
CHAT_SYSTEM to 2. You will need to compile, start up the game, do
a @shutdown, change the value of CHAT_SYSTEM in options.h to 3,
recompile, and start the game up again. This ensures that the new
database is will be correctly saved.

     The initial default chat channels are listed in chat.c. You
can change these defaults at runtime (read the help for @channel,
and put the relevant commands on the @startup of an object).

     For now, you can probably leave bigrams.h untouched. You do
not need to change any of the other header files.

     You next have to make sure you're set up for the IPC you need
for your machine. The only IPC package which is guaranteed to work
is bsd.c.  The concentrator code is only current through approximately
version 1.16, and the xenix and xsocket code have not even been glanced
at for the last year and a half. If you choose to use them and somehow
manage to get them to work, please let Amberyl know so your changes can
be included in the next release.

     Now, finally, edit the Makefile.  Pick your compiler, memory
options, and other stuff.  For now, you will not want to run with
any RWHO options, so just use the default there.

     Do a "make install". This will build all the necessary files, and
set up some symbolic links for the restart script.  You will need to use
"mkindx" to build the indexes for news and help (and events, if you're
using that). The format is 'mkindx <text file> <index file>'.  You must
change the index file every time you change its associated text file.
The restart script automatically builds the indexes for you every time
you start the game. You do not need to worry about the "extract"
and "dump" utilities.

     The next step is to create your configuration file. In the game
directory is a file called "mush.conf". You may want to rename it
<your MUSH name>.conf.  This is a list of all runtime configuration
options with their default settting. Change them as you see fit.
IMPORTANT: do not _delete_ any parameters. They all need to be there.

     Next, you must edit the restart script. You will probably want
to change the INDB to indb.Z, and you almost definitely will to change
GAMEDIR. That should be whatever directory the restart script is in.
You will also probably need to change the name of the configuration file,
as well as possibly some of the other file names, depending on what you
chose in the config file. The restart script is written for sh, and
assumes a fairly standard Berkeley UNIX setup. If you're on a HP-UX
or SysV machine, for example, you may need to change the restart script
a bit (the ps options, for example).

     You should now be ready to start the game.  This distribution comes
packaged with a basic database - a God character, starting room, and master
room. This file is called game/data/minimal.db.Z.  You will probably want
to rename this file  to indb.Z (it needs to be the same as INDB in the
restart script).  The god character "One" has a default password of
"one", which you should change immediately (via @password).
options.h has the Master Room as #2 by default; in the provided database,
this room is created for you.

      If you're doing the chat conversion, remember that you need to
@shutdown and recompile with CHAT_SYSTEM changed to 3. Otherwise, you
should be set -- all you have to do now is customize the .txt files in
the game directory.

      The logfiles in the "log" directory generally contain useful
information. You will probably want to read your main logfile (defined
in the restart script) every time, since errors and other important
messages get printed to that logfile.

      When you are ready to go public, you should send mail to Scott
Goehring ([e-mail]), and ask to be put on his
MUDlist. Tell him the email address of the administrator (probably you),
the type of MUD (PennMUSH version whatever), the name of the MUSH, the
address, and any other relevant information, like its theme.

      If you have any problems, feel free to contact Amberyl via email
at [e-mail]. PLEASE include the version number you are
attempting to compile, the type of machine and operating system you are
using, and, if possible, the address of the MUSH.

============================================================================

III.  Conversion Guide (previous users)

      This MUSH version will read databases along the main branch of
MUSH evolution -- TinyMUD, vanilla TinyMUSH, MicroMUSH, and all
Pern/PennMUSH versions. If you need to convert a TinyMUSH 2.0 database,
please contact Amberyl, and she'll mail you an extension to 2.0 that will
dump a 1.50-readable flatfile.

      It might be necessary to do some conversions, depending on
what version you are converting from. The "ADD_<whatever>" options
in options.h govern the conversions; to convert, compile with whatever
ADD options you need defined, start up the game, do a @shutdown,
recompile with those options turned off, and then start the game again.

      If you are upgrading from 1.50.p7, you will not need to do any
conversions. From PennMUSH 1.50 versions before patchlevel 7, you will
need to define ADD_POWERS. If you have a 1.x MUSH database dating before
1.50, you should ftp PennMUSH 1.50 patchlevel 5, and convert your database
to 1.50 format, then follow the directions for ADD_POWERS above.

      If you do not do the conversion correctly, when you attempt
to start the game, you will get an error message like "bad attribute"
in the logfile, and the MUSH will refuse to start. You will definitely
want to back up your database before attempting to do any conversions.

      If you are upgrading from patchlevel 5 or earlier, please note
that  in patchlevel 6, compile-time configuration options were moved
into options.h, and the restart script was written in sh instead of csh.

      Please read the CHANGES files. They contain a large amount of
important information. A list of code changes that affect players is
given in news.txt. You may want to clip that section for your own news file.

============================================================================

IV.   Additional Options

      There are two additional major things which you can change. One
is to use a tuned bigram table; using this will probably improve internal
compression, thus reducing the amount of memory the MUSH takes up. Until
your MUSH reaches 5000 objects, this is probably not bothering with.
Details on how to get a tuned bigram table are given in the file BIGRAMS.

       MUSH also provides an interface for connecting to an RWHO server.
RWHO servers allow players to see who is connected to many MUDs via
telnet, or, if the administrator allows it, via a direct RWHO command
from the game.

       There are three possible options for RWHO. The first is not to
use it. This is the default, and you can feel free to just keep it
that way.

        The second option is to send login info to a remote RWHO server.
This option is highly recommended, since it is simple and painless. It
uses UDP to send the info, so there will be no slowdown of the game by
enabling this. There are several steps to getting this set up.

        1)  Contact the administrator of an RWHO server and ask if you can
            send login info to that server. The names of administrators
            are generally in the MUDlist posted to rec.games.mud.misc.
            One of the larger servers is run by Moira (Jennifer Smith,
            [e-mail]).  Try sending her mail, with
            the name and address of your MUSH.
        2)  The administrator will probably send you mail back within a
            day or two, with additional info. You will get a password
            and an address for the RWHO server. Change the appropriate
            things in options.h and recompile. You should then be set.

        The third option is to send info to the RWHO server, AND enable
reading RWHO server info from within the MUSH (via the RWHO command).
This is a BAD idea unless the RWHO server and the MUSH are on the same
LOCAL network. The reason for this is that retrieving RWHO info uses
a stream port, and the MUSH could freeze if the net between it and the
RWHO server went down. If you MUST run this way, you might want to talk
to [e-mail] about how to set up your own RWHO server.

    Another option you may want to consider is allowing your MUSH
to receive remote messages from other MUSHes via rpage. This uses UDP,
and does not slow down or otherwise endanger the MUSH.  If you wish to
do this, you should contact Amberyl to get the rpage code, and compile
with ALLOW_RPAGE defined.

        You should then contact the Gods of some other MUSHes. You will
need, for each MUSH, to agree on a password. You will need to do a:
rpage/add OtherMUSH password=address.of.other.mush
and the God of the other MUSH will need to do a:
rpage/add YourMUSH password=address.of.your.mush

        The name of the MUSH must be the same as that in "@version",
aliases are allowed for additional entries, but one entry MUST be the
name the MUSH uses in its conf file.

        The final thing you may want to think about is compiling announce.c
That is a port announcer; if your MUSH ever goes down, you can set that up,
and a message will be given to a person attempting to connect to that port.
Read that file for details. It is not an official MUSH piece of code; rather,
it is a freely distributable program available via anonymous FTP that is
included in this code because it happens to be fairly useful.

============================================================================

V.      Trouble-shooting

        If you ever run into trouble, the your first reaction should
ALWAYS be to back up your database. indb.Z.old is the file that the
MUSH saves indb.Z to when the game, restarted, indb.Z is the file that
the MUSH loaded at startup, and outdb.Z is the file to which the MUSH
is currently dumping the database.

        You can tell if a dump is (theoretically) complete by doing a
"zcat <database file name> | tail -10".  The last line should read
"***END OF DUMP***". If it doesn't, your database has been truncated
for some reason. Check the logfile. Possible causes include a full
process table, a full disk partition, or running out of disk quota.

        Occasionally the dump process may dump core. This is caused
by some sort of corruption in an attribute, normally. You can tell
if the dump process has died by looking in your data directory; you
will see something like "outdb.Z.#5#". Wait a few moments and check
on the file again. If it has grown, then the game is in the process
of a normal dump. If it hasn't, and there's a core file, then something
has gone wrong. You should definitely shout a warning that building
is not being saved.

        To attempt to fix the problem, do a @dbck to take care of any
possible minor weirdness in the database, then try doing a "@dump/paranoid",
and reading the checkpoint logfile (default is log/checkpt.log). This is
slow, but it will write out an uncorrupted database, and tell you what it
fixed. Back up that database and indb.Z, then figure out what you're going
to do next: you can take the game down with a kill -9, or attempt to
manually fix the problem by either @destroying the offending object, or
attempting to reset the attributes on the object that are causing a problem.
If "@dump/paranoid" dies, you are more or less out of luck.

        To fix weirdness in numerical fields, such as location or flags,
use the "examine/debug" and "@fixdb" commands.  Don't do this unless you
know precisely what you're trying to fix, since it's possible to produce
database inconsistencies which will panic, crash, or hang the server.

        The game may crash from time to time. It will generate a
core file, usually; if you don't limit the coredumpsize or strip the
executable, you should be able to get some useful information out of
it, using a debugger. Amberyl is interested in stack traces. You can
do a stack trace in the following manner: Go into the directory where
you keep your source code, and type
<name of debugger> netmud game/core
If you don't call your executable "netmud", substitute in whatever
you do call it.

        You are looking for variables set to bizarre values - attempts
to access objects that aren't there, attempts to use pointers which
point to nothing, and the like.

        If you are using the "adb" debugger (don't do this unless
you really have absolutely nothing else available), you will see
nothing. It's loaded and ready, though. Type "$c". This will print
out a list of the functions it called. Type "$q" to quit. You can't
really get much more useful information out of adb.

        If you are using the "dbx" debugger, type "where" to see
the stack trace. You can move through it using "up" and "down",
and see exactly what the sequence of calls was. You can also use
"print <variable name>" to see the value of a variable at the
time the game crashed.  The "gdb" debugger is similar to "dbx"; with
that, you can abbreviate "print" as "p".

        Amberyl appreciates news of any bugs found, and any patches
that have been written to deal with them. She is also interested in
any extensions that people make to the code, and requests that ones
that are of more than just local interest be sent to her for inclusion
in the next release of this code.

        One important thing to remember is, if the MUSH refuses to
start, there is probably a good reason. Check the MUSH log, and the
core file, if there is one. Make sure to back up your database before
attempting to restart -- remember that every time it restarts, it
overwrites indb.Z.old. If you restart three times and somehow manage
to trash your database each time (for example, a full process table
zero'ing out your files), you won't have a backup to restart from,
unless you've backed up your database before trying!

        This code has been tested on a fairly wide variety of machines
and operating systems. JT Traub (Moonchilde, [e-mail]) ran
it on a DECstation; Ambar ([e-mail]) later worked with JT on
stabilizing the code on a NeXT, where it eventually was rock-solid stable.
Currently, Amberyl is working on a Sun SPARC-series workstation, and
doing fairly extensive testing on an IBM RS/6000, a MicroVAX II, and
various SGI workstations. There's no real reason why PennMUSH shouldn't
compile on a machine with a BSD-derived operating system and an ANSI
compliant compiler (non-ANSI compilers should also work, but no guarantees
are given here). It should probably should run under anything System V-ish
with some juggling of #include files and other  modifications (tell Amberyl
if you needed to make major changes to get it working).
        This version of code was sucessfully compiled on a several different
Sun Sparc-series computers running SunOS 4.1.1, 4.1.2, and 4.1.3, a NeXT
running Mach 2.1, some DEC machines running various versions of Ultrix, an
IBM RS/6000 running AIX 3.2, and some SGI workstations running IRIX 4.0.5.
Previous versions have worked on an HP 9000/720 running HP-UX 8.0 and
various 486 PCs running Linux; this version should, as well.

        If you have serious problems, contact Amberyl and she will
try to help you. Email is the best way to get a fast response;
in an emergency, you can bother her on a MUD, but for code problems,
email will probably get you a better response.

============================================================================

VI.     Comments

        These are in the first person.  :)

        I've been working with this code for a year and a quarter now.
I can't claim that it's particularly elegant or inspired; all I can say
is that it works (most of the time), and that I've had fun writing it.
I'm also hoping that it's quite readable; the sections I've added or
revised tend to be quite heavily commented.

        I'm willing to support this code and listen to whatever complaints,
suggestions, and screams for help you might have, with a great deal of
patience (usually). I am interested in any changes that you might make to
the code, as well as anything you might need to have done in order to get
PennMUSH to compile and run on "unusual" systems.

        A number of people have been contributed a lot, directly and
indirectly, to PennMUSH; many of them are credited in copyright.h.
Read the file and embarrass them the next time you see them.  ;)

        PennMUSH 1.50 patchlevel 3 contains the promised parser rewrite.
A great deal of the code is derived or directly taken from the TinyMUSH 2.0
parser; credit goes to JT Traub (Moonchilde) and Glenn Crocker (Wizard)
for writing the thing in the first place. In most cases, the 1.50 parser
should now be functionally identical to the parser in TinyMUSH 2.0.9;
see the news file for a brief summary of the changes. Major differences
between the 1.50 and 2.0 parsers are almost certainly bugs, and should
be reported to me.

        I am trying to keep extending the functionality of the server,
while optimizing and rewriting things wherever possible.  Ideas for
new features, and other discussion of this server should be sent to
the 1.50 mailing list:  [e-mail]
I'm also working on another project, with several friends at Penn;
we're writing an X-windows-based graphical MUD called PennMAX, for
fun and academic credit.

        I do have a life, though, and academics/job/social stuff
take priority. Thus, don't get too upset if it takes me a while to
add your pet hack.  :)  I'm generally happy to discuss code and
life in general, though, so if you see me on a MUSH, feel free to
say hi.

        Enjoy your MUSH, and feel free to email for help.


              --  Lydia Leong  ([e-mail])
                  "Amberyl" just about everywhere